Implementing Flexible UI One-Step-Screenflow

Table of Contents

 

Applies To:

Knowledge Management 6.0

Summary

Developing customer flexible UI components is important to extending the standard KM navigation UI with customer-specific functionality. UICommands are components executing an action for a certain content management resource object. This implies having a simple screenflow logic, e.g. for offering a confirmation screen to the end user. The One-Step-Screenflow API offers the possibility to implement a screenflow logic for custom-based UICommands.

 

Prerequisites and Relevant Knowledge Management APIs

A prerequisite for developers starting to use flexible UI One-Step-Screenflow is an understanding of the concepts described in Repository Framework Concepts (RCO) and advanced knowledge of flexible UI component development and deployment, including CollectionRenderer and ResourceRenderer.

This tutorial describes the use of flexible UI One-Step-Screenflow in customer flexible UI commands. The following Knowledge Management API package is used in the sample implementation:

Coding in Detail

This example shows the implementation of a One-Step-Screenflow in a UICommand for single actions.

Flexible UI One-Step-Screenflow can be used in flexible UI commands, based on the ICommand interface or AbstractCommand class for single item actions. For MassCommands the interface IMassCommand or the abstract class AbstractMassCommand must be used.

The call stack of a single screenflow process will be shown in the sequence diagram below.

The necessary API for this implementation is: com.sapportals.wcm.rendering.uicommand.AbstractCommand and com.sapportals.wcm.rendering.uicommand.ISimpleExecution.

We recommend extending the AbstractCommand and implementing the ISimpleExecution interface in one component:

public class SimpleUICommand extends AbstractCommand 
        implements ISimpleExecution {
:
}

Extending AbstractCommand

As a prerequisite to implementing a UICommand with screenflow the setTargetParameters() and getTargetParameters() have to be implemented by the custom UICommand. Both methods handle the data between the command object and the proxy controller of the framework. Information of the selected content management resource is exchanged through these methods. The passed List oject (java.util.List) contains the parameters returned by the string array of the getTargetParameters() method. The order is kept like in the string array object.

A simple implementation of this method could store the parameters in member variables of the command:

    public void setTargetParameters(List list, IResourceContext ctxt) 
                throws WcmException {
        this.context = ctxt;
        this.values = list;
    }

A mandatory return value of the getTargetParameters() method is the current RID object for which this UICommand is executed.

    public String[] getTargetParameters() throws WcmException {
        return new String[]{ this.getResource().getRID().getPath() };
    }

The RID object is passed back again by the proxy controller later in the screenflow process.

The most important method to be implemented in the UICommand is the execute(IScreenflowData) method. This method defines which Screenflow component is rendered and executes the first step of the screenflow. It renders the specified control for users input. 

    public IRenderingEvent execute(IScreenflowData sfd) throws 
        WcmException {

The content of the Screenflow component can be defined by the developer. He can place every HTMLB component control to the ConfirmComponent. In this example a simple TextView component is used.

        TextView tv = new TextView("tvid");
        tv.setText("Do you really want to do this ?");

Create a new ConfirmComponent with an OK and Cancel button for a decision by the end user.

        ConfirmComponent cc = new ConfirmComponent(
            ConfirmComponent.OK_CANCEL, 
            this.context.getLocale(),
            tv
        );

Get the current RID object out of the parameters list retrieved from the proxy controller.

        String sRid = (String)this.values.get(0);
        RID rid = RID.getRID(sRid, null);

Create the new screenflow for the specified screenflow data, this alias of this command, the RID object and the ConfirmComponent. 

        OneStepScreenflow oscf = new OneStepScreenflow(
            sfd,
            this.getAlias(),
            rid,
            cc
        );

It is mandatory to pass the alias of the UICommand to get a valid callback from the framework.

The screenflow's first step is executed and will display the ConfirmComponent on the user's screen. 

        return oscf.execute();

After the first execution the process continues within the ISimpleExecution interface implementation.

Methods available in this abstract class:

Method

Purpose

execute(IScreenflowData)

This method executes the screenflow. It is triggered by the Flexible UI framework.

setTargetParameters()

Passes information from the proxy controller to the UICommand

getTargetParameters()

Return a string array of all persistent data passed to the proxy controller

Implementing ISimpleExecution

The ISimpleExecution interface is the callback of the screenflow component. It is called after the user's input is done and the server roundtrip is triggered.

The method to be implemented by this interface:

public IRenderingEvent execute(IResource res, Event event) throws 
        WcmException {

The event passed by the flexible UI framework must be an instance of a ConfirmEvent. 

    if (event instanceof ConfirmEvent) {
        ConfirmEvent cce = (ConfirmEvent)event;

The ConfirmEvent contains the user's input and offers methods and static variables to evaluate the user information. Within this method the concrete action on the resource should take place. The resource object is also passed by the framework.

        if (ConfirmEvent.CHOICE_YES.equals(cce.getChoice())) {
            // do the action here ...
            
            return new InfoEvent(Status.OK, "Done !");
        } else if (ConfirmEvent.CHOICE_NO.equals(cce.getChoice())) {
            return ConfirmComponent.onNo(event, 
                res.getContext().getLocale());
        } else if (ConfirmEvent.CHOICE_CANCEL.equals(cce.getChoice())) {
            return ConfirmComponent.onCancel(event,
            res.getContext().getLocale());
        }    
    }

This method must return a valid UI event, which renders the status of this action to the status line of a KM iView.

 return new InfoEvent(Status.ABORT, "Aborted.");

Methods to be implemented by this interface:

Method

Purpose

execute(IResource, Event)

Execute method of the ISimpleExecute interface. It is the callback method of the framework if the screenflow is passed.

Configuration

After deployment of the UICommand within a valid PAR file structure, the technical mapping has to be carried out in the user interface configuration of the KM configuration iView.

The mapping from a Java class to a component alias can be carried out at Content Management -> User Interface -> Commands -> UICommands. Create a new entry for the custom UICommand.

A unique alias and a valid Java class must be provided. The Java class specified here must implement the ICommand interface and contain the methods mentioned above.

The UICommand is now registered in the KM infrastructure and can be added to any UICommandGroup of the KM.

Sample UI Command with One-Step-Screenflow

The following archive contains a valid and deployable SAP NetWeaver Developer Studio project based on KM API of NW04 SPS 4, which shows the steps described above in a whole example.

Example com.sap.netweaver.kmc.flexui_screenflow.zip